9  Making a Code Appendix

An aspect of Open Science is being transparent and open about your code. This is especially important when engaged in data analysis. Making your code available helps convey a sense of trustworthiness in you as an author and analyst.

Making your code available does not mean that your code must be perfect. No one expects code to perfect. The idea in sharing the code that you used is so that other people can examine your code and reproduce your results. They (and your future self) can then look at those results with what you’ve written and make sure everything is coherent and logical.

When working in a single document, we can leverage Quarto’s powers to automatically create an appendix of all of your code chunks. In essence, we’ll make use of Quarto’s ability to take your code chunks and moved them to the end of the document. This helps to make your data analysis focused on what you’re finding/discovering without cluttering the body of your report with distracting code.

9.1 Code for the Appendix

To create a Code Appendix, you will need to go to the bottom of your Quarto document. There you’ll want to copy what appearss in Listing 9.1.

Listing 9.1: Code Chunk for Creating Code Appendix

\{\{< pagebreak >\}\}  
# Code Appendix
```{r}
#| label: codeAppend
#| ref-label: !expr knitr::all_labels()
#| echo: true
#| eval: false

```

CautionRemove the Backslashes

In Listing 9.1, you’ll notice that there are four backslashes (i.e., \) that appear in the first line (with pagebreak). You will need to remove these backslashes when you copy this code into your document. They appear here so that you can see this line of code.

Outside of the four code chunk options (and one empty line), there should be nothing else in your final code chunk. Additionally, there should be nothing except empty lines after the closing three backticks for this code chunk. After putting this code into your Quarto document, the next time you render the file, your Code Appendix will get generated. Additionally, as you edit your file and re-render, the Code Appendix will automatically update.

9.2 Recommended Strategies for a Great Code Appendix

To ensure that your Code Appendix looks good, you should treat it just like the body of your report. That is, you should generate the Code Appendix and then proof read it! Look through the appendix and look for any problematic pieces.

Some things to watch out for:

• Do all of the lines of code make sense?
• Did you use meaningful names for all objects and functions?
• Did you use code comments to create a structure to the Code Appendix?
• Did you use code comments to help convey what each part of your code (i.e., each code chunk) is supposed to do?
• Did you lint your QMD file and take care of any issues?
• Do you have any lines that are too long? That is, that extend off the page?

A good strategy for the first four is to pretend you’ve never seen the code before and then try to make sense of what the code does. If you find yourself struggling and/or giving an invalid explanation, then that is a sign for improving these items.

For the remaining two items, we have a couple of tools we can use.

9.2.1 Linting Your QMD

Remember that we can lint our QMD file just like an R script. To do so follow these steps:

1. Save your QMD file.
2. Create a new R script file.
3. In this new file, load the {lintr} package via a library call. (If needed, install the {lintr} package.)
4. Write the command lint(filename = "/path/to/file.qmd") where you replace /path/to/file.qmd with the appropriate file path to your QMD file.
5. Run the commands.

You should get a report that will tell you what your lint issues are. The report will provide line numbers for your QMD file; if you click on an entry, it should take you to that particular problem.

9.2.1.1 Course Project .lintr File

In the Course Project template, we included a .lintr file that is pre-configured to match the coding style used throughout the assignments (i.e., the BOAST Style). Delete this file to use the tidyverse Style.

9.2.2 Dealing with Long Code Lines

One of the harder aspects to manage for a Code Appendix is handling long code lines. Remember, we generally don’t want a line of code to exceed 80 characters. This can be quite challenging, especially if you are working with data stored online and have long URLs.

Linting will help identify some long lines. A way to help minimize long lines is to not try to fit all arguments into a single line. Generally, give each argument their own line.

9.2.2.1 Long URLs and File Paths

If you have long URLs or file paths, there are a couple of things we can do.

For a long file path, look to see if you can shorten that path by moving the file. Keep in mind that the setting up a R Project allows you put all necessary files into a dedicated space and then use relative file paths. Long file paths are generally a sign of using absolute file paths and/or overly complicated directory structures. Simplify!

For long URLs, there isn’t much we can do to change these. If you don’t need real-time access to what’s located at the URL, consider downloading what is there and adding the file to your Project directory.

Alternatively, we can break a long URL into pieces and then use paste0 to glue them back together. For example, consider the long URL:

https://docs.google.com/spreadsheets/d/19xQnI1cBh6Jkw7eP8YQuuicMlVDF7Gr-nXCb5qbwb_E/edit?usp=sharing

We could break this into parts on one of the forward slashes such as shown in Listing 9.2.

Listing 9.2: Example of Breaking a Long URL

```{r}
#| label: breakingURLs
#| lst-label: lst-breakURL
#| lst-cap: "Example of Breaking a Long URL"

library(googlesheets4)

# Example showing breaking a long URL ----
baseURL <- "https://docs.google.com/spreadsheets/d/"
specificURL <- "19xQnI1cBh6Jkw7eP8YQuuicMlVDF7Gr-nXCb5qbwb_E/edit?usp=sharing"

# Example showing how to use the parts ----
gs4_deauth()
armedForces <- read_sheet(
  ss = paste0(baseURL, specificURL)
)
```

9.2.3 Wrapping Long Code Lines

By default, Quarto will not wrap long code lines like it does narrative text. However, depending on what output file you are rendering to, there are some approaches we can take.

TipBest Practice

Before relying on automatic wrapping of long lines of code, you should take every step you can think of to eliminate long lines.

9.2.3.1 HTML Outputs

For HTML output files, wrapping long lines of code is a simple as adding a new key: value pair to our YAML headers. As shown in #lst-htmlWrap we will add the code-overflow key with the value wrap nested under the html key (under the format key).

Listing 9.3: YAML Options for Wrapped Code

---
format:
  html:
    code-overflow: wrap
---

9.2.3.2 PDF Outputs

For PDF output files, wrapping long lines of code is trickier. Here are a couple of options but keep in mind that they are experimental and should be tested and double-checked.

9.2.3.2.1 Option 1: Add Header Includes

The first option we have is to include some additional options in our YAML header for PDF outputs. Depending on how current your LaTeX/TinyTex installation is, you might run into some problems.

To use this option, you’ll need to add the code in Listing 9.4 to your YAML Header. Then when you render to PDF, long line of code should get wrapped.

Listing 9.4: YAML Options for Wrapped Code

---
format:
  pdf:
    include-in-header: 
      text: |
        \usepackage{fvextra}
        \DefineVerbatimEnvironment{Highlighting}{Verbatim}{
          commandchars=\\\{\},
          breaklines, breaknonspaceingroup, breakanywhere
        }
---

If you get an error message when rendering that the system could not find fvextra.sty, then you’ll need to update your installation and potentially manually install the fvextra LaTeX package: (tinytex::tlmgr_install("fvextra")).

9.2.3.2.2 Option 2: Use typst

Instead of using format: pdf in your YAML header, use format: typst. This will use the Typst open source engine to create the PDF. However, be warned that Typst is under active development and not everything functions as anticipated. For instance, the sizing of images may not be what you expect.